Creating your first Tarantool database

First, let’s install Tarantool, start it, and create a simple database.

You can install Tarantool and work with it locally or in Docker.

Using a Docker image

For trial and test purposes, we recommend using the official Tarantool images for Docker. An official image contains a particular Tarantool version and all popular external modules for Tarantool. Everything is already installed and configured in Linux. These images are the easiest way to install and use Tarantool.

Note

If you’re new to Docker, we recommend going over this tutorial before proceeding with this chapter.

Launching a container

If you don’t have Docker installed, please follow the official installation guide for your OS.

To start a fully functional Tarantool instance, run a container with some minimal options:

$ docker run \
  --name mytarantool \
  -d -p 3301:3301 \
  -v /data/dir/on/host:/var/lib/tarantool \
  tarantool/tarantool:latest

This command runs a new container named mytarantool. Docker starts it from an official image named tarantool/tarantool:latest, with the latest Tarantool version and all external modules already installed.

Tarantool will accept incoming connections on localhost:3301. You can start using it as a key-value storage right away.

Tarantool persists data inside the container. To make your test data available after you stop the container, this command also mounts the host’s directory /data/dir/on/host (you need to specify here an absolute path to an existing local directory) in the container’s directory /var/lib/tarantool (by convention, Tarantool in a container uses this directory to persist data). Through this, all changes made in the mounted directory on the container’s side are applied to the host’s disk.

Tarantool’s database module in the container is already configured and started. You don’t need to do it manually, unless you use Tarantool as an application server and run it with an application.

Note

If your container terminates immediately after starting, follow this page for a possible solution.

Attaching to Tarantool

To attach to Tarantool that runs inside the container, run:

$ docker exec -i -t mytarantool console

This command:

Instructs Tarantool to open an interactive console port for incoming connections.
Attaches to the Tarantool server inside the container under the admin user via a standard Unix socket.

Tarantool displays a prompt:

tarantool.sock>

Now you can enter requests on the command line.

Note

On production machines, Tarantool’s interactive mode is designed for system administration only. We use it for most examples in this manual, because it is convenient for learning.

Creating a database

While we’re attached to the console, let’s create a simple test database.

First, create the first space (named tester):

tarantool.sock> s = box.schema.space.create('tester')

Format the created space by specifying field names and types:

tarantool.sock> s:format({
              > {name = 'id', type = 'unsigned'},
              > {name = 'band_name', type = 'string'},
              > {name = 'year', type = 'unsigned'}
              > })

Create the first index (named primary):

tarantool.sock> s:create_index('primary', {
              > type = 'tree',
              > parts = {'id'}
              > })

This is a primary index based on the id field of each tuple. TREE is the most universal index type. To learn more, check the documentation on Tarantool index types.

Insert three tuples (our name for records) into the space:

tarantool.sock> s:insert{1, 'Roxette', 1986}
tarantool.sock> s:insert{2, 'Scorpions', 2015}
tarantool.sock> s:insert{3, 'Ace of Base', 1993}

To select a tuple using the primary index, run:

tarantool.sock> s:select{3}

The terminal screen now looks like this:

tarantool.sock> s = box.schema.space.create('tester')
---
...
tarantool.sock> s:format({
              > {name = 'id', type = 'unsigned'},
              > {name = 'band_name', type = 'string'},
              > {name = 'year', type = 'unsigned'}
              > })
---
...
tarantool.sock> s:create_index('primary', {
              > type = 'tree',
              > parts = {'id'}
              > })
---
- unique: true
  parts:
  - type: unsigned
    is_nullable: false
    fieldno: 1
  id: 0
  space_id: 512
  name: primary
  type: TREE
...
tarantool.sock> s:insert{1, 'Roxette', 1986}
---
- [1, 'Roxette', 1986]
...
tarantool.sock> s:insert{2, 'Scorpions', 2015}
---
- [2, 'Scorpions', 2015]
...
tarantool.sock> s:insert{3, 'Ace of Base', 1993}
---
- [3, 'Ace of Base', 1993]
...
tarantool.sock> s:select{3}
---
- - [3, 'Ace of Base', 1993]
...

To add a secondary index based on the band_name field, run:

tarantool.sock> s:create_index('secondary', {
              > type = 'tree',
              > parts = {'band_name'}
              > })

To select tuples using the secondary index, run:

tarantool.sock> s.index.secondary:select{'Scorpions'}
---
- - [2, 'Scorpions', 2015]
...

To drop an index, run:

tarantool> s.index.secondary:drop()
---
...

Stopping a container

When the testing is over, stop the container politely:

$ docker stop mytarantool

This was a temporary container, and its disk/memory data were flushed when you stopped it. But since you mounted a data directory from the host in the container, Tarantool’s data files were persisted to the host’s disk. Now if you start a new container and mount that data directory, Tarantool will recover all of the data from disk and continue working with the persisted data.

Using a package manager

For production purposes, we recommend that you install Tarantool via the official package manager. You can choose one of three versions: LTS, stable, or beta. An automatic build system creates, tests and publishes packages for every push into a corresponding branch at Tarantool’s GitHub repository.

To download and install the package that’s appropriate for your OS, start a shell (terminal) and enter the command-line instructions provided for your OS at Tarantool’s download page.

Starting Tarantool

To start working with Tarantool, start a terminal and run this:

$ tarantool
$ # by doing this, you create a new Tarantool instance

Tarantool starts in interactive mode and displays a prompt:

tarantool>

Now you can enter requests on the command line.

Note

On production machines, Tarantool’s interactive mode is designed for system administration only. We use it for most examples in this manual because it is convenient for learning.

Creating a database

Here is how to create a simple test database after installation.

To let Tarantool store data in a separate place, create a new directory dedicated for tests:
```
$ mkdir ~/tarantool_sandbox
$ cd ~/tarantool_sandbox
```
You can delete the directory when the tests are completed.
Check if the default port that the database instance will listen to is vacant.

In versions before 2.4.2, during installation the Tarantool packages for Debian and Ubuntu automatically enable and start the demonstrative global example.lua instance that listens to the 3301 port by default. The example.lua file showcases the basic configuration and can be found in the /etc/tarantool/instances.enabled or /etc/tarantool/instances.available directories.

However, we encourage you to perform the instance startup manually, so you can learn.

Make sure the default port is vacant:
1. To check if the demonstrative instance is running, run:
```
$ lsof -i :3301
COMMAND    PID USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
tarantool 6851 root   12u  IPv4  40827      0t0  TCP *:3301 (LISTEN)
```
2. If it is running, kill the corresponding process. In this example:
```
$ kill 6851
```
To start Tarantool’s database module and make the instance accept TCP requests on port 3301, run:
```
tarantool> box.cfg{listen = 3301}
```

Create the first space (named tester):

tarantool> s = box.schema.space.create('tester')

Format the created space by specifying field names and types:

tarantool> s:format({
         > {name = 'id', type = 'unsigned'},
         > {name = 'band_name', type = 'string'},
         > {name = 'year', type = 'unsigned'}
         > })

Create the first index (named primary):
```
tarantool> s:create_index('primary', {
         > type = 'tree',
         > parts = {'id'}
         > })
```
This is a primary index based on the id field of each tuple. TREE is the most universal index type. To learn more, check the documentation on Tarantool index types.

Insert three tuples (our name for records) into the space:

tarantool> s:insert{1, 'Roxette', 1986}
tarantool> s:insert{2, 'Scorpions', 2015}
tarantool> s:insert{3, 'Ace of Base', 1993}

To select a tuple using the primary index, run:

tarantool> s:select{3}

The terminal screen now looks like this:

tarantool> s = box.schema.space.create('tester')
---
...
tarantool> s:format({
         > {name = 'id', type = 'unsigned'},
         > {name = 'band_name', type = 'string'},
         > {name = 'year', type = 'unsigned'}
         > })
---
...
tarantool> s:create_index('primary', {
         > type = 'tree',
         > parts = {'id'}
         > })
---
- unique: true
  parts:
  - type: unsigned
    is_nullable: false
    fieldno: 1
  id: 0
  space_id: 512
  name: primary
  type: TREE
...
tarantool> s:insert{1, 'Roxette', 1986}
---
- [1, 'Roxette', 1986]
...
tarantool> s:insert{2, 'Scorpions', 2015}
---
- [2, 'Scorpions', 2015]
...
tarantool> s:insert{3, 'Ace of Base', 1993}
---
- [3, 'Ace of Base', 1993]
...
tarantool> s:select{3}
---
- - [3, 'Ace of Base', 1993]
...

To add a secondary index based on the band_name field, run:

tarantool> s:create_index('secondary', {
         > type = 'tree',
         > parts = {'band_name'}
         > })

To select tuples using the secondary index, run:

tarantool> s.index.secondary:select{'Scorpions'}
---
- - [2, 'Scorpions', 2015]
...

Now, to prepare for the example in the next section, try this:

tarantool> box.schema.user.grant('guest', 'read,write,execute', 'universe')

Connecting remotely

In the request box.cfg{listen = 3301} that we made earlier, the listen value can be any form of a URI (uniform resource identifier). In this case, it’s just a local port: port 3301. You can send requests to the listen URI via:

telnet,
a connector,
another instance of Tarantool (using the console module), or
tt administrative utility.

Let’s try (3).

Switch to another terminal. On Linux, for example, this means starting another instance of a Bash shell. You can switch to any working directory in the new terminal, not necessarily to ~/tarantool_sandbox.

Start another instance of tarantool:

$ tarantool

Use net.box to connect to the Tarantool instance that’s listening on localhost:3301”:

tarantool> net_box = require('net.box')
---
...
tarantool> conn = net_box.connect(3301)
---
...

Try this request:

tarantool> conn.space.tester:select{2}

This means “send a request to that Tarantool instance, and display the result”. It is equivalent to the local request box.space.tester:select{2}. The result in this case is one of the tuples that was inserted earlier. Your terminal screen should now look like this:

$ tarantool

Tarantool 2.6.1-32-g53dbba7c2
type 'help' for interactive help
tarantool> net_box = require('net.box')
---
...
tarantool> conn = net_box.connect(3301)
---
...
tarantool> conn.space.tester:select{2}
---
- - [2, 'Scorpions', 2015]
...

You can repeat box.space...:insert{} and box.space...:select{} (or conn.space...:insert{} and conn.space...:select{}) indefinitely, on either Tarantool instance.

When the testing is over:

To drop the space: s:drop()
To stop tarantool: Ctrl+C or Ctrl+D
To stop Tarantool (an alternative): the standard Lua function os.exit()
To stop Tarantool (from another terminal): sudo pkill -f tarantool
To destroy the test: rm -r ~/tarantool_sandbox

Version:

Creating your first Tarantool database

Using a Docker image

Launching a container

Attaching to Tarantool

Creating a database

Stopping a container

Using a package manager

Starting Tarantool

Creating a database

Connecting remotely